Manage Activities with Effort APIs

Introductions

Application Programming Interfaces (APIs) allow different software systems to integrate and work together seamlessly. In Effort, APIs serve as intermediaries that enable you to manage your business activities from external systems, such as third-party applications or services.

In this tutorial, we will guide you step-by-step through the process of using Effort APIs to effectively manage employee data, including creating and updating employee records and works.

The list of activities are outlined below.

Understanding Effort APIs

Effort APIs likely provide a set of endpoints (URLs) and methods (such as GET, POST, PUT, DELETE) that allow you to interact with the Effort system programmatically. These APIs typically enable actions such as creating new employee records, updating existing employee data, retrieving employee information, managing customer records and works, and so on.

For more information on endpoint URLs, request bodies, and other related data, refer to the EFFORT Web Services APIs documentation.

Authentication and Authorization

To access the Effort APIs, you need to authenticate yourself and obtain authorization. This often involves obtaining an API key or token from the Effort system, which serves as a credential to authenticate your requests. For more information, reach out to the Spoors DevOps team.

Create Employees using API

In this section, you will find the steps to create a new employee record in the Effort platform from an external system using API. Here, we are using the Postman tool as an external system to execute this task.

Prerequisites

Before you create an employee using API, ensure you have the following:

  • companyId: To get the companyId, follow the steps below:
    1. Log in to Effort.
    2. Go to Web App > Home.
    3. Hover your cursor towards the gear icon located beside the No Action Items button.
      APIDocument 3
    4. You can find the company ID in the URL located at the bottom of the page.
      APIDocument 4
  • calendarId: To get the calendarId, follow the steps below:
    1. Log in to Effort.
    2. Go to App Builder > Employees > Calenders.
    3. You can find the Calendar ID under the ID against the required calendar.
      APIDocument 5

To create a new employee record from the Postman tool, follow the steps below:

  1. Go to EFFORT Web Services APIs.
  2. Scroll down to the Employees section and copy the request body from the Create Employee method.
    APIDocument 1
  3. Now, Open Postman and provide the following:
    • Method: POST
    • Endpoint URL: https://externalapis.spoors.in/effortx/service/create/employee?userName=
    • Query Parameter: userName (Provided by the Spoors DevOps team).
    • Authorization: Provided by the Spoors DevOps team.
    • Request Body: Paste the request body that you copied earlier.

    APIDocument 2
  4. Modify the employee details, such as companyId, calendarId, empNo, empFirstName, and so on.
    APIDocument 6
    As you can see above, here we are creating an employee named Pavan Rathode with EmpNo as 1221.
  5. Click Send.
    Once you click Send, your request is validated. If your request is correct, you will receive the successful response as shown below:
    APIDocument 7
  6. Now, we will go to Effort and check if the employee record has been created. Go to Web App > Employees.
    APIDocument 8
    As you can see above, the employee record is created.

Create Work using API

In this section, you will find the steps to create a new work record in the Effort platform from an external system using API. Here, we are using the Postman tool as an external system to execute this task.

  1. Log in to Effort.
  2. Go to App Builder > Processes.
  3. Click either Activity Process or Checklist Process as per your requirement, and then click the required process in which you want to create a work.
    APIDocument 9
    For this tutorial, we are creating a work for a sample process called Doctors Management.
  4. On the Manage Actions page, scroll down to the Utilities section and click Generate Sample JSON.
    APIDocument 10
  5. On the next page, you will find the following:
    • Request URL
      APIDocument 11
      Note: To get the userName for your organization, reach out to the Spoors DevOps team.
    • Request Body
      APIDocument 12
    • Sample Success Response
      APIDocument 13
    • Sample Failure Response
      APIDocument 14
  6. Copy the Request URL and Request Body.
  7. Now, open Postman and provide the following:
    • Method: POST
    • Endpoint URL: https://api.spoors.in/effort6/service/api/all?userName=
    • Authorization: Provided by the Spoors DevOps team.
    • Request Body: Paste the request body that you copied earlier.
  8. Update the values in the request body, such as externalId, ff_Starts, ff_Ends, and so on.
    APIDocument 15
    As you can see above, here we are creating a work against a customer named Pavan.
  9. Click Send.
    Once you click Send, your request is validated. If your request is correct, you will receive the successful response as shown below:
    APIDocument 16
  10. Now, we will go to Effort and check if the new work record has been created. Go to Web App > Specific Process.
    APIDocument 17
    As you can see above, a new work record has been created.

Modify Work using API

In this section, you will find the steps to modify an already created work in the Effort platform from an external system using API. Here, we are using the Postman tool as an external system to execute this task.

  1. In the previous section, we have created a work against a process called Doctors Management. Now, we will modify the same process using API. You can use the same request body used for creating the work.
  2. Update the values in the request body as per your requirement.
    APIDocument 19

    As you can see above, we have changed the customer name. Previously, it was Pavan; now it is Rohit.

  3. Click Send.
    Once you click Send, your request is validated. If your request is correct, you will receive the successful response as shown below:
    APIDocument 16
  4. Now, we will go to Effort and check if the work record has been modified. Go to Web App > Specific Process.
    APIDocument 20
    As you can see above, the work record has been modified.

Complete Activity using API

In this section, you will find the steps to complete an activity of an already created work in the Effort platform from an external system using API. Here, we are using the Postman tool as an external system to execute this task.

Prerequisites

Before you begin, ensure you have the following:

  • actionSpecId: To get the actionSpecId, follow the steps below:
    1. Log in to Effort.
    2. Go to App Builder > Processes > Specific Processes > Manage Activities/Subtasks.
    3. On the Modify Activity Process page, hover your cursor towards the activity for which you want to know the ID, right-click, and then click Inspect.
      APIDocument 22
    4. Copy the value against the workActionSpecId.
      APIDocument 23
  • workSpecId: To get the workSpecId, follow the steps below:
    1. Log in to Effort.
    2. Go to App Builder > Processes > Specific Processes.
    3. On the Process Actions page, copy the workSpecId from the URL.
      APIDocument 24
  • workId: To get the workId, follow the steps below:
    1. Log in to Effort.
    2. Go to Web App > Processes > Specific Processes.
    3. Under the Actions column, click the eye icon against the required work to view the work details.
      APIDocument 26
    4. Copy the work ID.
      APIDocument 25

To complete a work activity from the Postman tool, follow the steps below:

  1. Open Postman and provide the following:
    • Method: POST
    • Endpoint URL: https://externalapis.spoors.in/effortx/service/work/action/completion?userName=SalesUsecasedemo
    • Query Parameter: userName (Provided by the Spoors DevOps team).
    • Authorization: Provided by the Spoors DevOps team.
    • Request Body: Paste the following request body.
      [
    {
        "actionSpecId": 52445,
        "workSpecId": 13592,
        "workId": "35364178",
        "form": [
            {
                "ff_Remarks": "None",
                "ff_Lead_Classification": "Hot"
            }
        ]
    }
]
      Note: In the above request body, the form array contains the form fields to be filled as part of the activity. You can replace these fields with your form fields. To get the form JSON configured against the activity, go to App Builder > Forms > Click Required Form > Effort API Payload Format.
      APIDocument 27

    APIDocument 2
  2. Update the values in the request body as per your requirement.
    APIDocument 28
  3. Click Send.
    Once you click Send, your request is validated. If your request is correct, you will receive the successful response as shown below:
    APIDocument 29
  4. Now, go to Effort and check if the activity has been completed. Go to Web App > Specific Process > Click eye icon against the work.
    APIDocument 30
    As you can see above, the work activity has been completed.